Extension::CurlRequestTemplate Method

Syntax

Arguments

requestCharacter Pointer

Request defined as a JSON string or dot variable. Variable placeholders and SQL::Arguments can be used in the request definition. Variables use bracket syntax {variableName} and are specified in the variables parameter. SQL::Arguments are specified using colon syntax :variableName and are specified in the args parameter.

Special placeholders are also available for the namedResource:

Placeholder

Description

{namedresource.access_token}

The access token that was retrieved when the authentication, defined in the Named Resource, was performed.

{namedresource.resourceURL}

The base URL for the request as returned by the service when the authentication, defined in the Named Resource, was performed.

The request must have the following structure:

uristring

The request URI. See examples below for more information.

formobject

Required if the URI endpoint requires data submitted in a form format.

An object containing one or more properties that define data to submit in the request. Refer to the API documentation for the request endpoint for what data can be submitted.

bodyobjectstring

Required if the URI endpoint requires data submitted in the body of the request.

An object or string containing the body of the request. Refer to the API documentation for the request endpoint for format requirements for data submitted in the body.

headersobject

An object containing headers to include in the request. Required if required by the request endpoint.

authobject

This property is required if the URI requires authentication. Authentication can be one of two types: username (user) and password (pass) or a bearer token (bearer), either from a Named Resource or generated using other means (examples below).

bearerstring

Required if authentication uses a bearer token. Can use the special placeholder, {namedresource.access_token}, to get the token from the Named Resource provider (specified by the namedResource argument).

userstring

Required if authentication uses a user name and password. The authentication user name.

passstring

Required if authentication uses a user name and password. The authentication password.

namedResourceCharacter

A Named Resource. The Named Resource can contain information for authentication (such as authentication information for Salesforce or Google.) Named Resources are defined in Project Properties on the Web Projects Control Panel.

variablesCharacter Pointer

Default = null_value(). Defines values for variables used in the request. Can be specified as a dot variable, a JSON string, or one or more URI encoded name-value pairs in the format "variable_name=value" joined with an ampersand (&). E.g. "var1=value1&var2=value2". Required if request uses variables.

argsSQL::Arguments

Default = null_value(). A SQL::Arguments object that defines arguments used in the request. Required if request uses SQL::Arguments.

Returns

responseExtension::CurlResponse

The response returned by the call.

Description

Simple CURL request template, populated from optional named resource, variables and arguments, from request JSON or supplied properties.

When defining the URI and the headers in the JSON passed to the extension::curl::RequestTemplate() method, there are two special placeholders that you can use:

• {namedresource.access_token} - the access token that was retrieved when the authentication, defined in the Named Resource, was performed
• {namedresource.resourceURL} - the base URL for the request as returned by the service when the authentication, defined in the Named Resource, was performed.

The values for these placeholders are resolved by the specified Named Provider (see the namedResource variable in the example code below).

Sample Xbasic code showing how a REST API call is made to the Salesforce API.

(Assume that the authentication details for the Salesforce account have been saved in a Named Provider called salesforcetoken. )

Notice that the URI specified in the JSON string has an argument name in it (:id)

dim json as c = <<%json%
{
    "uri": "{namedresource.resourceurl}/services/data/v39.0/sobjects/Account/:id",
    "auth": {
        "bearer" : "{namedresource.access_token}"
    }
}
%json%
dim namedResource as c = "salesforcetoken"

'define the value of the arguments used in the URI
dim args as sql::arguments
args.add("id","0011N00001EBYRDQA5")

'instead of putting the account id in a sql::argument, we could have
'used a variable and referenced the variable in the URI as {accountNumber)
'instead of :id
'for example: /services/data/v39.0/sobjects/Account/{accountNumber}

dim vars as p
vars.accountNumber = "0011N00001EBYRDQA5"

dim response as extension::CurlResponse
response = extension::curl::RequestTemplate(json,namedResource,vars,args)

if response.content <> "" then
    dim json as c
    json = response.content
else
    'no response
end

Post Commands

Posting data with a simple body, like JSON, requires populating a "body" property.

Below is an example appending a range of values to a google sheet.

dim json as c = <<%json%
{
    "uri": "https://sheets.googleapis.com/v4/spreadsheets/{spreadsheetid}/values/{SheetName}!A1:D1:append?valueInputOption=USER_ENTERED",
    "body": { "range": "{SheetName}!A1:D1", "majorDimension": "ROWS", "values": [ [ "=ROW()-1" , "sam", "smith", "smithco"] ] },
    "auth" : {
       "bearer" : "{namedresource.access_token}"  
    },
    "headers" :  {
      "Content-Type" : "application/json"
    }
}
%json%
dim namedResource as c = "GoogleSheet"
dim vars as p
dim vars.spreadsheetid as c = speadsheetId
dim vars.SheetName as c = "Customers"
dim args as sql::arguments
dim response as extension::CurlResponse
response = extension::curl::RequestTemplate(json,namedResource,vars,args)
end

Multipart Forms

Posting data to a multipart form requires defining a 'form' property with an object that has user supplied names (to tag the items) and sub properties of either body (for embedded content), or filename (for files stored on disk to upload).

Both body and filename form 'parts' can include optional content length and content type. content-length of 'length' will calculate the length from the supplied input.

Below is an example of uploading a file to google drive.

dim json as c = <<%json%
{
    "uri": "https://www.googleapis.com/upload/drive/v3/files?uploadType=multipart",
    "form" : {
        "metadata" : {
           "body" : { "name" : "{remoteName}" , "parents" : [ "{folderId}" ] },
           "content-length" : "length"
        } ,
        "media" : {
            "filename" : "{localname}" ,
            "Content-Type" : "{mimetype}" 
        }
    },
    "auth" : {
       "bearer" : "{namedresource.access_token}"
    }
}
%json%
dim vars as p
dim vars.folderId as c = folderId
dim vars.remoteName as c = file.filename_parse(filename,"ne")
dim vars.localname as c = strtran(filename,chr(92),"/")
dim vars.mimetype as c = resolve_mime_type(file.filename_parse(filename,"e"))
dim args as sql::arguments
dim response as extension::curlresponse
response = extension::curl::RequestTemplate(json,namedResource,vars,args)
end